Skip to main content

Hesabe Payment Integration Guide

This guide will walk you through integrating Hesabe payment gateway into your application. Hesabe offers two integration methods: Direct Integration and Indirect Integration.

Prerequisites​

Before you begin, make sure you have:

  • Merchant account credentials from Hesabe
  • Access token for API authentication
  • Test environment access (for development)

Integration Methods​

1. Direct Integration​

Direct integration allows you to handle the payment process within your application's interface. This method gives you more control over the payment flow and user experience.

Features​
  • Complete control over the payment form
  • Custom UI/UX design
  • Higher level of customization
  • PCI DSS compliance required
Implementation Steps​
  1. Create a payment form in your application
  2. Collect payment details securely
  3. Send payment request to Hesabe API
  4. Process the response
  5. Handle success/failure scenarios

2. Indirect Integration​

Indirect integration redirects customers to Hesabe's secure payment page. This method is simpler to implement and doesn't require PCI DSS compliance.

Features​
  • Quick implementation
  • No PCI DSS compliance needed
  • Hesabe-hosted payment page
  • Automatic security handling
Implementation Steps​
  1. Create payment request
  2. Redirect to Hesabe payment page
  3. Handle the response callback

API Endpoint​

The base URL for Hesabe API v2.0 is:

https://api.hesabe.com/v2

Integration Steps​

1. Create Payment Request​

To initiate a payment, send a POST request to:

POST /payment
Request Headers​
{
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json"
}
Request Body​
{
  "amount": 10.000,
  "currency": "KWD",
  "order_id": "ORDER123",
  "description": "Product purchase",
  "response_url": "https://your-domain.com/callback",
  "failure_url": "https://your-domain.com/failure"
}
Response​
{
  "status": true,
  "code": 200,
  "message": "Success",
  "response": {
    "token": "PAYMENT_TOKEN",
    "checkout_url": "https://checkout.hesabe.com/pay/PAYMENT_TOKEN"
  }
}

2. Handle Payment Response​

After the payment is completed, Hesabe will redirect to your response_url with the following parameters:

https://your-domain.com/callback?payment_token=TOKEN&status=SUCCESS

3. Verify Payment Status​

To verify the payment status, send a GET request:

GET /payment/status?token=PAYMENT_TOKEN
Response​
{
  "status": true,
  "code": 200,
  "message": "Success",
  "response": {
    "order_id": "ORDER123",
    "amount": 10.000,
    "currency": "KWD",
    "status": "CAPTURED",
    "transaction_id": "TXN123456"
  }
}

Payment Status Codes​

Status CodeDescription
CAPTUREDPayment successful
FAILEDPayment failed
PENDINGPayment pending
CANCELLEDPayment cancelled

Error Handling​

Handle the following common error scenarios:

  • Invalid token
  • Expired token
  • Invalid amount
  • Network errors
  • System maintenance

Testing​

Use the following test card details in the sandbox environment:

Card Number: 4111 1111 1111 1111
Expiry: Any future date
CVV: Any 3 digits

Security Considerations​

  1. Always validate the payment response on your server
  2. Use HTTPS for all API calls
  3. Keep your access token secure
  4. Implement proper error handling
  5. Log all transactions for audit purposes
  6. Ensure PCI DSS compliance if using Direct Integration

Support​

For technical support or questions, contact Hesabe support: